home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 34 / Amiga Format CD34 (1998-11-20)(Future Publishing)(GB)[!][Christmas issue].iso / -seriously_amiga- / emulation / afid / afid.doc < prev    next >
Text File  |  1998-10-20  |  8KB  |  199 lines
  1. name:
  2.     afid - apple ][ file developer
  3.  
  4.  
  5. usage:
  6.     afid [file_image]
  7.  
  8.  
  9. synopsis:
  10.     This file describes version 1.1 of afid.
  11.  
  12.  
  13. description:
  14.  
  15.     afid is a utility which allows you to manipulate an Apple ][ DOS 3.3 disk
  16.     image.  It currently doesn't handle ProDOS disk images and only reads and
  17.     writes 35 track, 16 sector diskette images.
  18.  
  19.  
  20. new for version 1.1:
  21.  
  22.     1) Added a help message listing the commands.
  23.     2) Added the ability to load different file images from within afid,
  24.        so you no longer need to exit and enter with a new image.
  25.     3) Prompts the user when attempting to exit without saving a changed
  26.        disk image.
  27.     4) Added new commands like load, list, mode, type, lock/unlock, rename,
  28.        delete/undelete.
  29.  
  30.  
  31. instructions:
  32.  
  33.     afid provides a simple command line interface.  You start it up by giving
  34.     it the name of a disk image:
  35.  
  36.     afid file.dsk
  37.  
  38.     It then reads the disk image into memory, does a few sanity checks and
  39.     gives you the "] " prompt.  If you fail to include the name of the disk
  40.     image, afid will still come up, but you can't do anything until you load
  41.     a disk image.
  42.  
  43.     From within afid you can use the following commands:
  44.  
  45.     load image        - this loads the specified disk image from your host file
  46.                   system into afid memory.  You need to have a disk image
  47.               in memory in order to do anything in afid.  This command
  48.               enables you to successively load different disk images
  49.               into afid without the need of exiting and loading a new
  50.               image from the command line.  If you already have a
  51.               changed, unsaved disk image in memory, afid will prompt
  52.               you with a warning before complying with the request.
  53.               You can specify the full path name to the disk image if
  54.               it is not in the current directory.
  55.  
  56.     catalog        - show a directory listing of the files on the disk image.
  57.                   afid uses the same format as an apple ][ running DOS3.3.
  58.  
  59.     free        - display a map of free sectors and the number of free and
  60.                   allocated sectors.
  61.  
  62.     quit, exit        - leave afid.
  63.  
  64.     read file        - copy the given file from the disk image to a file on the
  65.                   host computer.  Path names are not allowed, so the file
  66.               will be placed in the current directory.  afid retains
  67.               the apple ][ file name so care must be taken that the
  68.               name is valid on the host computer file system. For
  69.               example, the file named I/O on an apple ][ disk will
  70.               cause great problems on a UNIX system.
  71.  
  72.     list file        - displays the specified file on the screen.  This should
  73.                   be a text file and you should have set the mode to text
  74.               or you will just get a bunch of garbage.
  75.  
  76.     write file        - copy the given file from the host computer onto the disk
  77.               image.  Path names are not allowed, so the file to be
  78.               written needs to be in the current directory.  afid
  79.               retains the apple ][ file name so care must be taken that
  80.               the name is valid on the apple ][.  Valid apple ][ file
  81.               names must start with a letter, be 1 to 30 characters in
  82.               length, and may contain any character typable from the
  83.               keyboard, except a comma.
  84.  
  85.     binary        - sets the translation mode for read/list/write to binary.
  86.                   Binary mode copies a file without any translation.  This
  87.               is the default setting.
  88.  
  89.     text        - sets the translation mode for read/list/write to text.
  90.               In text mode, files are translated as follows: 1) Text
  91.               files - CR <-> LF & Apple <-> ASCII  2) All other file
  92.               types generate a hex dump of the file.
  93.  
  94.     mode        - lists text/binary translation mode for read/write/list
  95.  
  96.     type file,X     - changes the file type to X where valid values of X are:
  97.               X = T, I, A, B, S, or R.  Note that this only changes
  98.               the entry in the directory.  The actual file is not
  99.               touched.  This command is used to restore the correct
  100.               file type of a file that has been written to a disk
  101.               image.  This is necessary because all binary writes
  102.               create B file types and all text writes create T file
  103.               types.  type is used to restore the file type to what
  104.               it was.  You can't use type to magically convert say
  105.               an Applesoft basic file into Integer basic.  The list
  106.               of valid file types is given below:
  107.  
  108.               CODE    Meaning            Hex Value
  109.               ----    ---------------        ---------
  110.                T    Text files            0
  111.                I    Applesoft BASIC            1
  112.                A    Integer BASIC            2
  113.                B    Binary programs            4
  114.                S    Symbol Tables            8
  115.                R    Relocatable Binary       10
  116.  
  117.     reorder        - switch disk sector order between DOS 3.3 (default) and
  118.               ProDOS.
  119.  
  120.     rename f1,f2    - rename file f1 to f2 on the disk image",
  121.  
  122.     lock file       - write protect a file on the disk image",
  123.  
  124.     unlock file     - unwrite protect a file on the disk image",
  125.  
  126.     delete file     - delete a file from the disk image.",
  127.  
  128.     undelete fil    - undelete a file from the disk image, if possible.",
  129.  
  130.     save image      - save the in-memory disk image to a file on the host
  131.               computer file system.
  132.             
  133.  
  134. Notes:
  135.  
  136.     "save" is important, and changes made with "write" will not be permanent
  137.     until you save the disk image.  File names are translated to all uppercase
  138.     on the Apple disk and to all lowercase on the UNIX end.  This is
  139.     convenient, but could be annoying.  I'm not sure that the text translation
  140.     is done correctly.  I just empirically judged that twiddling the top bit
  141.     was the right thing to do.  Binary file copy is a little hokey; pay no mind
  142.     to the extra stuff it spits out at you.  Disk block ordering can be a
  143.     little tricky.  Basically, if you make the disk image on a machine running
  144.     ProDOS, you'll have to re-order the sectors.  This means that probably
  145.     anything extracted from a Shrinkit archive will need to be reordered. It
  146.     can be hard to tell since the most obvious symptom is a shortened catalog
  147.     which is not a lot different from a normally short catalog.
  148.  
  149.     The free command spits out some crap about the sector mask.  You can ignore
  150.     it, but knowledgeable folks could help me out.  I gather that the mask
  151.     allows you to specify sectors which cannot be used, but I've never seen a
  152.     mask that was usable.  What's wrong?
  153.  
  154.     I've compiled afid on a Sun sparcstation with gcc and on an Amiga with
  155.     SAS C 5.10.  It should be fairly portable as I tryed to write it in ANSI C
  156.     and stay away from vendor specific additions.  I hope this inspires someone
  157.     to create a ProDOS version.
  158.  
  159.  
  160. Things to do:
  161.  
  162.     File reads should do something smart like paying attention to the file
  163.     type.  Also need to add translations for Integer and Applesoft Basic.
  164.     Right now we only handle text and binary.
  165.  
  166.     A warning that a preexisting file is going to be overwritten could be put
  167.     in.  A more robust way of overwriting a file needs to be added.  Right
  168.     now the sectors aren't cleared first, so if the file you are overwriting
  169.     is larger than what you replace it with, the file size will remain the same.
  170.  
  171.     A warning that the disk blocks are out of order could be put in.
  172.  
  173.     Options to switch the file-name mapping on and off would be nice.
  174.  
  175.     A file-duplicating mechanism could be useful if you ever should run into
  176.     files with holes.  Sector allocation is not done in the same way as DOS 3.3
  177.     (not so bad) and may not be very efficient at times (not so good).
  178.  
  179.     Working with two disk images and swapping files back and forth would be
  180.     nice.
  181.  
  182.     Adding a 'more' style paging mechanism for list is definitely a necessity.
  183.  
  184.     Preventing the creation of file names with invalid characters is a concern.
  185.  
  186.     The code could use some cleaning up, for sure.  I'd try and completely
  187.     localize things like the VTOC accesses and come up with a few master
  188.     directory scanning and file scanning loops instead of duplicating the code
  189.     here and there.
  190.  
  191.     Fix any bugs, but that goes without saying.
  192.  
  193.     Anybody want to create a ProDOS version?
  194.  
  195.  
  196. source:
  197.     The latest version sh